/**
 * @file 浏览历史记录相关类型定义
 * @description 定义浏览历史记录的数据结构和接口类型，供主进程和渲染进程共享使用
 * @author 黄敏
 * @version 1.0.0
 * @since 2025-08-06
 */

/**
 * 浏览记录表结构
 */
export interface BrowsingHistory {
  /** 主键ID，自增 */
  id?: number
  /** 完整的 URL 地址 */
  url: string
  /** 页面标题 */
  title?: string
  /** 网站图标 URL */
  favicon_url?: string
  /** 最后一次增加访问次数的时间 (JavaScript 时间戳，毫秒) */
  visit_time: number
  /** 访问次数 */
  visit_count: number
  /** 创建时间 (JavaScript 时间戳，毫秒) */
  created_at: number
  /** 更新时间 (JavaScript 时间戳，毫秒) */
  updated_at: number
}

/**
 * 创建浏览记录的输入参数
 */
export interface CreateBrowsingHistoryInput {
  /** 完整的 URL 地址 */
  url: string
  /** 页面标题 */
  title?: string
  /** 网站图标 URL */
  favicon_url?: string
}

/**
 * 更新浏览记录的输入参数
 */
export interface UpdateBrowsingHistoryInput {
  /** 记录ID */
  id: number
  /** 页面标题 */
  title?: string
  /** 网站图标 URL */
  favicon_url?: string
  /** 访问次数 */
  visit_count?: number
  /** 最后一次增加访问次数的时间 (JavaScript 时间戳，毫秒) */
  visit_time?: number
}

/**
 * 查询浏览记录的参数
 */
export interface QueryBrowsingHistoryParams {
  /** URL 模糊匹配 */
  url_pattern?: string
  /** 标题模糊匹配 */
  title_pattern?: string
  /** 开始时间 (JavaScript 时间戳，毫秒) */
  start_time?: number
  /** 结束时间 (JavaScript 时间戳，毫秒) */
  end_time?: number
  /** 返回结果数量限制 */
  limit?: number
  /** 偏移量 */
  offset?: number
  /** 排序字段 */
  order_by?: 'visit_time' | 'visit_count' | 'created_at' | 'updated_at'
  /** 排序方向 */
  order_direction?: 'ASC' | 'DESC'
}

/**
 * 数据库操作结果
 */
export interface DatabaseResult<T = unknown> {
  /** 操作是否成功 */
  success: boolean
  /** 返回的数据 */
  data?: T
  /** 错误信息 */
  error?: string
  /** 影响的行数 */
  changes?: number
  /** 最后插入的行ID */
  lastInsertRowid?: number
}

/**
 * 搜索选项接口
 */
export interface BrowsingHistorySearchOptions {
  /** 返回结果数量限制 */
  limit?: number
  /** 是否在URL中搜索 */
  searchInUrl?: boolean
  /** 是否在标题中搜索 */
  searchInTitle?: boolean
  /** 时间范围 */
  timeRange?: {
    /** 开始时间 (JavaScript 时间戳，毫秒) */
    start?: number
    /** 结束时间 (JavaScript 时间戳，毫秒) */
    end?: number
  }
}

/**
 * 浏览历史记录API接口
 * @description 定义渲染进程可用的浏览历史记录操作接口
 */
export interface BrowsingHistoryAPI {
  // 删除操作
  deleteRecord: (id: number) => Promise<DatabaseResult<void>>
  deleteRecords: (ids: number[]) => Promise<DatabaseResult<void>>
  clearAllRecords: () => Promise<DatabaseResult<void>>

  // 查询操作
  findById: (id: number) => Promise<DatabaseResult<BrowsingHistory | null>>
  findByUrl: (url: string) => Promise<DatabaseResult<BrowsingHistory | null>>
  queryRecords: (params?: QueryBrowsingHistoryParams) => Promise<DatabaseResult<BrowsingHistory[]>>
  searchRecords: (keyword: string, limit?: number) => Promise<DatabaseResult<BrowsingHistory[]>>
  getRecentRecords: (limit?: number) => Promise<DatabaseResult<BrowsingHistory[]>>
  getMostVisitedRecords: (limit?: number) => Promise<DatabaseResult<BrowsingHistory[]>>
  getRecordCount: () => Promise<DatabaseResult<number>>

  // 修改操作
  updateRecord: (input: UpdateBrowsingHistoryInput) => Promise<DatabaseResult<BrowsingHistory>>

  // 便捷方法
  search: (
    query: string,
    options?: BrowsingHistorySearchOptions
  ) => Promise<DatabaseResult<BrowsingHistory[]>>
  getTodayRecords: (limit?: number) => Promise<DatabaseResult<BrowsingHistory[]>>
  getThisWeekRecords: (limit?: number) => Promise<DatabaseResult<BrowsingHistory[]>>
}

/**
 * 历史记录分组数据结构
 */
export interface HistoryGroup {
  /** 日期字符串 */
  date: string
  /** 该日期的历史记录项 */
  items: BrowsingHistory[]
}

/**
 * 虚拟滚动项类型
 */
export type VirtualScrollItem =
  | (BrowsingHistory & { type: 'history-item' })
  | { type: 'group-header'; date: string; count: number; id: string }

/**
 * 时间范围筛选类型
 */
export type TimeFilterRange = 'all' | 'today' | 'yesterday' | 'week' | 'month'

/**
 * 历史记录页面状态
 */
export interface HistoryPageState {
  /** 历史记录项列表 */
  historyItems: BrowsingHistory[]
  /** 加载状态 */
  loading: boolean
  /** 错误信息 */
  error: string | null
  /** 总记录数 */
  totalCount: number
  /** 搜索查询 */
  searchQuery: string
  /** 选中的项目ID列表 */
  selectedItems: number[]
  /** 当前时间筛选 */
  currentTimeFilter: TimeFilterRange
}

/**
 * 分页参数
 */
export interface PaginationParams {
  /** 当前页码 */
  page: number
  /** 每页项目数 */
  itemsPerPage: number
  /** 是否还有更多数据 */
  hasMore: boolean
}
